home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr10 / boxit010.zip / BOXIT.DOC next >
Text File  |  1993-06-24  |  18KB  |  476 lines
  1.                                  BoxIt!
  2.                               Version 0.10
  3.  
  4.                 For The SemWare Editor 1.00 Pre-Release
  5.  
  6.                            George J. De Bruin
  7.  
  8.                           ╒═════════════════╕
  9. ──────────────────────────┤Table Of Contents├──────────────────────────────────
  10.                           ╘═════════════════╛
  11.  
  12.     Introduction
  13.     Installing BoxIt!
  14.     Using BoxIt!
  15.         Side Toggles
  16.         Gap Settings
  17.         Line Settings
  18.     Quick Key Reference
  19.     Error Messages
  20.     History
  21.     Author Bio. & Contacting
  22.         Contact Points
  23.         BoxIt Releases
  24.         Remuneration / Donations
  25.     Future Versions
  26. ───────────────────────────────────────────────────────────────────────────────
  27.  
  28.    ╒════════════╕
  29. ═══╡Introduction╞══════════════════════════════════════════════════════════════
  30.    ╘════════════╛
  31.  
  32.     Many of the editors available in both the shareware and commercial
  33.     markets today have a line drawing facility.  A number of popular
  34.     editors have extended this to a box drawing facility.
  35.  
  36.     This macro serves two purposes:
  37.  
  38.         (1) To implement a box drawing facility for TSE that is
  39.             integrated closely with the editor.
  40.  
  41.         (2) To provide a well documented example of a macro written in
  42.             the SAL macro language. (This
  43.  
  44.     Permission is granted to the user of this macro to modify and
  45.     distribute modified versions of BoxIt!  See source code for
  46.     conditions applying to modified versions of BoxIt!
  47.  
  48.     ╒════════════════╕
  49. ════╡Installing BoxIt╞═════════════════════════════════════════════════════════
  50.     ╘════════════════╛
  51.  
  52.     Installation is easy.  You may do it in any way you chose! <grin>
  53.  
  54.     The .mac file supplied is exactly the same as the source provided.
  55.     It was compiled with the current version of TSE (indicated on the
  56.     cover page of the documentation, and in the source code), and is
  57.     bound to <Ctrl F1>, while the Main Menu is bound to <Alt F1>.  All
  58.     you have to do is load it through the Macro / Load command on the
  59.     menu, or by adding a LoadMacro() command to the appropriate location
  60.     in your se.s file (and re-burning it into the TSE).
  61.  
  62.     Another way to add it to TSE is the use the '#include' directive in
  63.     your se.s file.  If you do so, you will need to remove the '#include
  64.     ['Boxit.Key'] at the end of the BoxIt.S file, and add key bindings
  65.     to your se.key file.
  66.  
  67.     Note: the '#include' method of adding BoxIt! to TSE may not be too
  68.     appealing to some.  As of version 0.10, BoxIt! has grown to
  69.     approximately 11K in size (due primarily to the menu changes and the
  70.     new help system).
  71.  
  72.     Please consult the TSE documentation if you need help with loading
  73.     macros, or modifying the se.s or se.key file.  (Or consult a SemWare
  74.     representative, or me.)
  75.  
  76.        ╒════════════╕
  77. ═══════╡Using BoxIt!╞═════════════════════════════════════════════════════════
  78.        ╘════════════╛
  79.  
  80. Using BoxIt! is easy.  Just follow these steps:
  81.  
  82.     (1) Column mark where you want the box.
  83.  
  84.     (2) Pull up the BoxIt! Menu (<ALT F1>).
  85.  
  86.     (3) Set the Side Toggles, Gaps Settings, and Line Type to your
  87.         preferences.
  88.  
  89.     (4) Select BoxIt! from the menu.
  90.  
  91. To draw another box using the same settings:
  92.  
  93.     (1) Column mark where you want the box.
  94.  
  95.     (2) Press <Ctrl F1>.
  96.  
  97. More information on specific options can be found in the next sections
  98. of the documentation, or the help system.
  99.  
  100.        ╒════════════╕
  101. ═══════╡Side Toggles╞═════════════════════════════════════════════════════════
  102.        ╘════════════╛
  103.  
  104. The Side Toggles menu is used to turn each side of the box On or Off.
  105. Each side may be set individually using the Top, Bottom, Left and Right
  106. toggles. Additionally, all sides may be set at the same time using the
  107. Global selection.
  108.  
  109. The Global selection has an extra option: Invert. Inverting the sides
  110. changes all settings that were On to Off, and vice versa. For example,
  111. if the toggles were set like this:
  112.  
  113.                            ┌───────────────┐
  114.                            │ Global [  On] │
  115.                            ├───────────────┤
  116.                            │ Top     [Off] │
  117.                            │ Bottom  [Off] │
  118.                            │ Left    [ On] │
  119.                            │ Right   [ On] │
  120.                            └───────────────┘
  121.  
  122. After selecting the Global, Invert option, the menu would look like
  123. this:
  124.  
  125.                            ┌───────────────┐
  126.                            │ Global [ Inv] │
  127.                            ├───────────────┤
  128.                            │ Top     [ On] │
  129.                            │ Bottom  [ On] │
  130.                            │ Left    [Off] │
  131.                            │ Right   [Off] │
  132.                            └───────────────┘
  133.  
  134. The top and bottom sides have been turned on, while the left and right
  135. sides have been turned off.  Note that the Global selection now says
  136. 'Inv' next to it, indicating that you selected the inversion operation.
  137.  
  138. This is useful if you want to quickly draw a box where two sides have
  139. one type of line (say the top and right sides), while the other sides
  140. have a different type of line.  For example:
  141.  
  142.                               ╓──────────┐
  143.                               ║          │
  144.                               ╚══════════╛
  145.  
  146. Combining this feature with the user defined line type opens many
  147. possibilities.
  148.  
  149.        ╒════════════╕
  150. ═══════╡Gap Settings╞═════════════════════════════════════════════════════════
  151.        ╘════════════╛
  152.  
  153. The Gap Settings menu is used to adjust the amount of space between your
  154. marked block and the box BoxIt will draw for you.  Each side may be set
  155. individually using the Top, Bottom, Left and Right options.
  156. Additionally, the gap may be set for all sides at once using the Global
  157. option.
  158.  
  159. For example, if the Gap Settings menu looked like this:
  160.  
  161.                             ┌──────────────┐
  162.                             │Global [    0]│
  163.                             ├──────────────┤
  164.                             │Top    [    2]│
  165.                             │Bottom [    2]│
  166.                             │Left   [    1]│
  167.                             │Right  [    1]│
  168.                             └──────────────┘
  169.  
  170. You would get a box that looks like this (assuming the inner box was the
  171. column block):
  172.  
  173.                             ╔══════════════╗
  174.                             ║              ║
  175.                             ║┌────────────┐║
  176.                             ║│            │║
  177.                             ║│            │║
  178.                             ║│            │║
  179.                             ║└────────────┘║
  180.                             ║              ║
  181.                             ╚══════════════╝
  182.  
  183. Not that there is only 1 space between the block and the box.  This is
  184. the way BoxIt! works.  Just remember this short table:
  185.  
  186.                         ┌─────────────────────┐
  187.                         │        Lines Between│
  188.                         │Gap     Box and Block│
  189.                         ├─────────────────────┤
  190.                         │ 0      Within Block │
  191.                         │ 1           0       │
  192.                         │ 2           1       │
  193.                         │ 3           2       │
  194.                         │...         ...      │
  195.                         └─────────────────────┘
  196.  
  197. Now, assuming we wanted all of the gaps set to 1, we would use the
  198. global option to set them:
  199.  
  200.                             ┌──────────────┐
  201.                             │Global [    1]│
  202.                             ├──────────────┤
  203.                             │Top    [    1]│
  204.                             │Bottom [    1]│
  205.                             │Left   [    1]│
  206.                             │Right  [    1]│
  207.                             └──────────────┘
  208.  
  209. And our box would look like this (again, assuming the inner box was our
  210. block):
  211.  
  212.                             ╔══════════════╗
  213.                             ║┌────────────┐║
  214.                             ║│            │║
  215.                             ║│            │║
  216.                             ║│            │║
  217.                             ║└────────────┘║
  218.                             ╚══════════════╝
  219.  
  220.        ╒═════════════╕
  221. ═══════╡Line Settings╞════════════════════════════════════════════════════════
  222.        ╘═════════════╛
  223.  
  224. The Line Settings menu allows you to chose the style of line that you
  225. want to draw your box with. This features uses the standard line type
  226. settings supported by TSE:
  227.  
  228.     Single:       ┌────┐
  229.  
  230.     Double Top:   ╒════╕
  231.  
  232.     Double Side:  ╓────╖
  233.  
  234.     Double Both:  ╔════╗
  235.  
  236.     ASCII:        +-|
  237.  
  238.     Eraser
  239.  
  240.     User-defined: [■]
  241.  
  242. The user defined selection can be set to any character you wish to draw
  243. your box with.
  244.  
  245. You can use the Eraser option to remove boxes that you have drawn.  The
  246. easiest way to accomplish this is to
  247.  
  248.     (1) Select the box with a column block.
  249.     (2) Set the Line Type to Eraser.
  250.     (3) Set Global Gaps to 0.
  251.     (4) Set Global Side Toggles ON.
  252.  
  253. Then execute BoxIt.
  254.  
  255.        ╒═══════════════════╕
  256. ═══════╡Quick Key Reference╞══════════════════════════════════════════════════
  257.        ╘═══════════════════╛
  258.  
  259. Below is a short chart of the keys used by BoxIt:
  260.  
  261. <Alt F1>         BoxIt! Menu Bar
  262. <Ctrl F1>        Execute BoxIt! (Draw Box)
  263.  
  264. These keys are provided as short-cuts to navigating the menus:
  265.  
  266. <Ctrl G><G>      Set Global Gap
  267. <Ctrl G><T>      Set Top Gap
  268. <Ctrl G><B>      Set Bottom Gap
  269. <Ctrl G><L>      Set Left Gap
  270. <Ctrl G><R>      Set Right Gap
  271.  
  272. <Ctrl S><G>      Side Global Setting
  273. <Ctrl S><T>      Side Top Toggle
  274. <Ctrl S><B>      Side Bottom Toggle
  275. <Ctrl S><L>      Side Left Toggle
  276. <Ctrl S><R>      Side Right Toggle
  277.  
  278.        ╒══════════════╕
  279. ═══════╡Error Messages╞═══════════════════════════════════════════════════════
  280.        ╘══════════════╛
  281.  
  282. BoxIt! has a grand total of 3 error messages. Below is a short
  283. explanation of them:
  284.  
  285. No Column Block In File
  286. ═══════════════════════
  287.     Currently BoxIt! only supports column blocks (<ALT K> in TSE's
  288.     standard interface).
  289.  
  290.     This message appears when there is either no column block in the
  291.     current file, or if there is no block in the current file.
  292.  
  293.     BoxIt aborts in this condition.  All settings are left as they were,
  294.     and the block (if there was one) is still marked.
  295.  
  296.  
  297. Cursor Not In Block
  298. ═══════════════════
  299.     The cursor needs to be placed somewhere inside the marked area.
  300.  
  301.     This is an adopted standard among the TSE Beta testers and macro
  302.     authors.  It's primary purpose is to keep users from accidentally
  303.     performing an action they didn't mean to.
  304.  
  305.     BoxIt aborts in this condition.  All settings are left as they were,
  306.     and the block is still marked.
  307.  
  308.  
  309. Cannot Insert Box At or Before Beginning of Line
  310. ═══════════════════════════════════════════════
  311.     This error occurs most often when the left column of the block -
  312.     left gap is < 1. Currently, BoxIt! does *not* insert spaces at the
  313.     beginning of a line if it needs to.
  314.  
  315.     A later version may support this.
  316.  
  317.     BoxIt aborts in this condition.  All settings are left as they were,
  318.     and the block is still marked.
  319.  
  320.  
  321.  
  322.     ╒═══════╕
  323. ════╡History╞══════════════════════════════════════════════════════════════════
  324.     ╘═══════╛
  325.  
  326. Version     Date        Comments
  327. ───────────────────────────────────────────────────────────────────────────────
  328. 0.01        03/22/93  ∙ Initial coding of macro.  Very simple implementation.
  329. 0.02        03/24/93  ∙ Fixed bug that affects using macro in overwrite
  330.                         mode.  Insert is now set to On when macro is
  331.                         executed, and reset on exit.
  332.                       ∙ Added: Side Toggles for Top, Bottom, Left and
  333.                         Right sides.
  334.                       ∙ Added: Box Gap to all adjusting space between
  335.                         the block and the box.
  336.                       ∙ Added: Menu.  Allows setting all of the options,
  337.                         including the line pattern.  Also allows calling
  338.                         BoxIt.
  339.                       ∙ Added: Global Variables for Box edge toggles and
  340.                         Box gap.
  341. 0.03        06/10/93  ∙ First public release of BoxIt!
  342.                       ∙ Changed names of several procedures to resolve
  343.                         conflicts with internal TSE procedures.
  344.  
  345. 0.04 - 0.09 Were not released.
  346.  
  347. 0.10        06/24/93  ∙ Fixed bug that caused total lock-up of TSE when
  348.                         current row - gap < 1.
  349.                       ∙ BoxIt! now inserts as many lines as needed at
  350.                         the beginning and end of a buffer.
  351.                       ∙ Fixed bug that caused total lock-up of TSE when
  352.                         current column - gap < 1.  Boxit! now returns
  353.                         an error message "Cannot Insert Box At or Before
  354.                         Beginning of Line."
  355.                       ∙ Changed to menu-bar structure.
  356.                       ∙ All menu items have a help line message attatched.
  357.                       ∙ Added: About menu.  Select '≡' from menu bar.
  358.                       ∙ Added: Help screen(s).  Select 'Help' from menu
  359.                         bar.
  360.                       ∙ Added: Gap settings for each side of box.
  361.                       ∙ Added: Global gap setting.
  362.                       ∙ Added: Global sides on/off toggle.
  363.                       ∙ Documentation over-haul. <g>
  364.                       ∙ Source code split into four files:
  365.                          BOXIT.S  : The main source code.
  366.                          BOXIT.MNU: The menus.
  367.                          BOXIT.HLP: Help Screens.
  368.                          BOXIT.KEY: Key Bindings.
  369.  
  370.        ╒═════════════════════════╕
  371. ═══════╡Author: Bio. & Contacting╞════════════════════════════════════════════
  372.        ╘═════════════════════════╛
  373.  
  374. George J. De Bruin has been a beta tester for the SemWare Editor for
  375. over a year and a half, and has hosted the Ilink Editors Conference for
  376. over two years.
  377.  
  378. Contact Points
  379. ══════════════
  380.  
  381. George may be reached on the following networks in the conferences
  382. listed:
  383.  
  384. RIME:       Qedit
  385. Ilink:      Qedit, Editors, Shareware
  386. Fido:       Qedit
  387. Intelec:    Qedit, Word Processing
  388. PlanoNet:   Reviews
  389. SmartNet:   Qedit
  390. MetroLink:  Qedit
  391. EchoNet:    Qedit
  392.  
  393. In addition, he may be reached at the following places:
  394.  
  395.     The SemWare BBS -- (404) 641-8968
  396.     Conference #4, TSE Questions.
  397.     Send Mail To: George De Bruin
  398.  
  399.     The Lunatic Fringe BBS -- (214) 235-5288
  400.     Conference #141, Get-Mo!
  401.     Send private message to: George De Bruin.
  402.  
  403.     Exec-PC -- (414) 789-4210
  404.     Send Email to: George De_Bruin
  405.  
  406.     8:930/13@RBBSNet routed through 8:930/1
  407.     NetMail To: George De Bruin
  408.  
  409. He may also be reached via the U.S. Postal Service at:
  410.  
  411.     George J. De Bruin
  412.     1414 Shiloh Rd. Box 511
  413.     Plano, TX 75074
  414.  
  415. He will also accept voice phone calls at:
  416.  
  417.     (214) 422-0266
  418.  
  419. during reasonable hours (Central Time Zone).  Because of an ever
  420. changing work schedule he cannot commit to hours when he will be
  421. available.
  422.  
  423. He is also unable to accept collect calls, or return calls.
  424.  
  425. BoxIt Releases
  426. ══════════════
  427.  
  428.     All future versions of BoxIt will be officially released on the
  429.     three BBS systems (SemWare, The Lunatic Fringe, and Exec-PC) listed
  430.     above.  BoxIt may also be downloaded from the author directly after
  431.     first calling him voice.  Terminal settings will be 2400 N-8-1.
  432.  
  433.     If you would like a copy sent to you on disk, please send a
  434.     pre-formatted disk and SASE to the address listed above.
  435.  
  436. Remuneration / Donations
  437. ════════════════════════
  438.  
  439.     BoxIt is distributed as freeware, with source code included.  No
  440.     payment is expected or required for it's use.
  441.  
  442.     However, donations are cheerfully accepted (especially since my HST
  443.     just died).  Any donations will be applied to a fund to purchase a
  444.     new modem.
  445.  
  446.     Note: Donations will not be used as a form of contract.  I will not
  447.           supply any extra services to anyone who does make a donation.
  448.           Heck, I may not even produce another version of BoxIt
  449.           (although I still have things on the list that I want to do).
  450.  
  451.     ╒═══════════════╕
  452. ════╡Future Versions╞══════════════════════════════════════════════════════════
  453.     ╘═══════════════╛
  454.  
  455.  
  456.     Below is a list of the features that are planned for future
  457.     versions. Features will be added to the list as they are suggested.
  458.     All features will be implemented as time permits.
  459.  
  460.         ■ Line marking.  Calculate longest line, and check for ample
  461.           left margin space.
  462.  
  463.         ■ Block history.  Allow user to restore block from a scroll-back
  464.           stack to ease making changes to existing boxes. (??????)
  465.  
  466.         ■ Overwriting text warning.
  467.  
  468.         ■ Inserting blank lines warning(s).
  469.  
  470.         ■ Quick Keys.  Menus will probably become cumbersome to some.
  471.           Need quick way to set options on the fly. (Partially
  472.           implemented now...not too well thought out, IMO).
  473.  
  474.         ■ Insert mode.  Allow text around box to be pushed left / right
  475.           and create blank lines for box where necessary.
  476.